<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Percepio Trace Recorder: Trace Internal Event Buffer APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Percepio Trace Recorder<span id="projectnumber">&#160;v4.10.3</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('group__trace__internal__event__buffer__apis.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle"><div class="title">Trace Internal Event Buffer APIs<div class="ingroups"><a class="el" href="group__trace__recorder__apis.html">Trace Recorder APIs</a></div></div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga64c5ba2b4aa958bd4da590c00277e089"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#ga64c5ba2b4aa958bd4da590c00277e089">xTraceInternalEventBufferAlloc</a> (uint32_t uiSize, void **ppvData)</td></tr>
<tr class="memdesc:ga64c5ba2b4aa958bd4da590c00277e089"><td class="mdescLeft">&#160;</td><td class="mdescRight">Allocates a data slot directly from the internal event buffer.  <br /></td></tr>
<tr class="separator:ga64c5ba2b4aa958bd4da590c00277e089"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaaf5da768c35025f53ce4d4c6c3e5d7fe"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#gaaf5da768c35025f53ce4d4c6c3e5d7fe">xTraceInternalEventBufferAllocCommit</a> (void *pvData, uint32_t uiSize, int32_t *piBytesWritten)</td></tr>
<tr class="memdesc:gaaf5da768c35025f53ce4d4c6c3e5d7fe"><td class="mdescLeft">&#160;</td><td class="mdescRight">Commits the last allocated block to the internal event buffer.  <br /></td></tr>
<tr class="separator:gaaf5da768c35025f53ce4d4c6c3e5d7fe"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga8efdf84edc7d4b3d8c516c57e0379e01"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#ga8efdf84edc7d4b3d8c516c57e0379e01">xTraceInternalEventBufferPush</a> (void *pvData, uint32_t uiSize, int32_t *piBytesWritten)</td></tr>
<tr class="memdesc:ga8efdf84edc7d4b3d8c516c57e0379e01"><td class="mdescLeft">&#160;</td><td class="mdescRight">Pushes data to the internal trace event buffer.  <br /></td></tr>
<tr class="separator:ga8efdf84edc7d4b3d8c516c57e0379e01"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gadacd640440d46ee4f0bea31d112acd67"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#gadacd640440d46ee4f0bea31d112acd67">xTraceInternalEventBufferTransferAll</a> (void)</td></tr>
<tr class="memdesc:gadacd640440d46ee4f0bea31d112acd67"><td class="mdescLeft">&#160;</td><td class="mdescRight">Transfers all internal trace event buffer data using the function xTraceStreamPortWriteData(...) as defined in trcStreamPort.h.  <br /></td></tr>
<tr class="separator:gadacd640440d46ee4f0bea31d112acd67"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga71c1dd2b171f8eb8968a4f159b5bd20f"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#ga71c1dd2b171f8eb8968a4f159b5bd20f">xTraceInternalEventBufferTransferChunk</a> (void)</td></tr>
<tr class="memdesc:ga71c1dd2b171f8eb8968a4f159b5bd20f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Transfer internal trace event buffer data through streamport.  <br /></td></tr>
<tr class="separator:ga71c1dd2b171f8eb8968a4f159b5bd20f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gab1e22d3a7a75cd53d9916ab2cc097075"><td class="memItemLeft" align="right" valign="top">traceResult&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__trace__internal__event__buffer__apis.html#gab1e22d3a7a75cd53d9916ab2cc097075">xTraceInternalEventBufferClear</a> (void)</td></tr>
<tr class="memdesc:gab1e22d3a7a75cd53d9916ab2cc097075"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears all trace events in the internal trace event buffer.  <br /></td></tr>
<tr class="separator:gab1e22d3a7a75cd53d9916ab2cc097075"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga64c5ba2b4aa958bd4da590c00277e089" name="ga64c5ba2b4aa958bd4da590c00277e089"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga64c5ba2b4aa958bd4da590c00277e089">&#9670;&#160;</a></span>xTraceInternalEventBufferAlloc()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferAlloc </td>
          <td>(</td>
          <td class="paramtype">uint32_t&#160;</td>
          <td class="paramname"><em>uiSize</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void **&#160;</td>
          <td class="paramname"><em>ppvData</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Allocates a data slot directly from the internal event buffer. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">uiSize</td><td>Allocation size </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">ppvData</td><td>Pointer that will hold the area from the buffer.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="gaaf5da768c35025f53ce4d4c6c3e5d7fe" name="gaaf5da768c35025f53ce4d4c6c3e5d7fe"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaaf5da768c35025f53ce4d4c6c3e5d7fe">&#9670;&#160;</a></span>xTraceInternalEventBufferAllocCommit()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferAllocCommit </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>pvData</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint32_t&#160;</td>
          <td class="paramname"><em>uiSize</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int32_t *&#160;</td>
          <td class="paramname"><em>piBytesWritten</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Commits the last allocated block to the internal event buffer. </p>
<p>For the sake of conformity this function accepts the same arguments as xTraceInternalEventBufferPush. These arguments are not used in the traditional sense since the alloc already managed these parts. This function simply marks the allocate stage as complete and ready for transfer.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">pvData</td><td>Pointer to data </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">uiSize</td><td>Size of data </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">piBytesWritten</td><td>Bytes written.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="gab1e22d3a7a75cd53d9916ab2cc097075" name="gab1e22d3a7a75cd53d9916ab2cc097075"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab1e22d3a7a75cd53d9916ab2cc097075">&#9670;&#160;</a></span>xTraceInternalEventBufferClear()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferClear </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Clears all trace events in the internal trace event buffer. </p>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ga8efdf84edc7d4b3d8c516c57e0379e01" name="ga8efdf84edc7d4b3d8c516c57e0379e01"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8efdf84edc7d4b3d8c516c57e0379e01">&#9670;&#160;</a></span>xTraceInternalEventBufferPush()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferPush </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>pvData</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint32_t&#160;</td>
          <td class="paramname"><em>uiSize</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int32_t *&#160;</td>
          <td class="paramname"><em>piBytesWritten</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Pushes data to the internal trace event buffer. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">pvData</td><td>Pointer to data </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">uiSize</td><td>Size of data </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">piBytesWritten</td><td>Bytes written.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="gadacd640440d46ee4f0bea31d112acd67" name="gadacd640440d46ee4f0bea31d112acd67"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gadacd640440d46ee4f0bea31d112acd67">&#9670;&#160;</a></span>xTraceInternalEventBufferTransferAll()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferTransferAll </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Transfers all internal trace event buffer data using the function xTraceStreamPortWriteData(...) as defined in trcStreamPort.h. </p>
<p>This function is intended to be called by the periodic TzCtrl task with a suitable delay (e.g. 10-100 ms).</p>
<p>In case of errors from the streaming interface, it registers a warning (TRC_WARNING_STREAM_PORT_WRITE) provided by xTraceErrorGetLast().</p>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ga71c1dd2b171f8eb8968a4f159b5bd20f" name="ga71c1dd2b171f8eb8968a4f159b5bd20f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga71c1dd2b171f8eb8968a4f159b5bd20f">&#9670;&#160;</a></span>xTraceInternalEventBufferTransferChunk()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">traceResult xTraceInternalEventBufferTransferChunk </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Transfer internal trace event buffer data through streamport. </p>
<p>This routine will attempt to transfer a chunk of existing data in the trace event buffer through the streamport. New data pushed to the trace event buffer during the execution of this routine will not be transfered.</p>
<p>When transferring a chunk which wraps the buffer, a singular transfer is made to avoid issuing dual writes. This configuration means that during wrapping, the chunk might be reduced in size even if there is more data at the start of the buffer. To transfer more data check piBytesWritten and issue multiple transfers if required.</p>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6 </li>
  </ul>
</div>
</body>
</html>
